<HTML>
<HEAD>
<TITLE>TSP (libtsp) - AFdReadData</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFACD">
<H2>AFdReadData</H2>
<HR>
<H4>Routine</H4>
<DL>
<DT>
int AFdReadData (AFILE *AFp, long int offs, double Dbuff[], int Nreq)
</DL>
<H4>Purpose</H4>
<DL>
<DT>
Read data from an audio file (return double values)
</DL>
<H4>Description</H4>
This routine returns a specified number of samples at a given sample offset
in an audio file.  The data in the file is converted to double format on
output.  The sample data in the file is considered to be preceded and
followed by zero-valued samples.  Thus if the sample offset is negative or
points to beyond the number of samples in the file, the appropriate number
of zero-valued samples is returned.  The file must have been opened using
routine AFopnRead.
<P>
The following program fragment illustrates the use of this routine to read
overlapping frames of data.  For the simpler case of sequential access to the
data without overlap, the variable Lmem should be set to zero.
<P>
<PRE>
  AFp = AFopnRead (...);
  ...
  Lmem =...
  Lframe =...
  Nadv = Lframe-Lmem;
  offs = -Lmem;
  while (1) {
    Nout = AFdReadData (AFp, offs, Dbuff, Lframe);
    offs = offs+Nadv;
    if (Nout == 0)
      break;
    ...
  }
</PRE>
<P>
On encountering an error, the default behaviour is to print an error message
and halt execution.
<H4>Parameters</H4>
<DL>
<DT>
&lt;-  int AFdReadData
<DD>
Number of data values transferred from the file.  On reaching the end of
the file, this value may be less than Nreq, in which case the last
elements are set to zero.  This value can be used by the calling routine
to determine when the data from the file has been exhausted.
<DT>
 -&gt; AFILE *AFp
<DD>
Audio file pointer for an audio file opened by AFopnRead
<DT>
 -&gt; long int offs
<DD>
Offset into the file in samples.  If offs is positive, the first value
returned is offs samples from the beginning of the data.  The file data
is considered to be preceded by zeros.  Thus if offs is negative, the
appropriate number of zeros will be returned.  These zeros before the
beginning of the data are counted as part of the count returned in Nout.
<DT>
&lt;-  double Dbuff[]
<DD>
Array of doubles to receive the Nreq samples
<DT>
 -&gt; int Nreq
<DD>
Number of samples requested.  Nreq may be zero.
</DL>
<H4>Author / revision</H4>
P. Kabal
/ Revision 1.2  2003/05/09
<H4>See Also</H4>
<A HREF="AFfReadData.html">AFfReadData</A>,
<A HREF="AFopnRead.html">AFopnRead</A>
</BODY>
</HTML>
